v0.6.2

Compare Source

Bugfix release: bumps rules_jvm_external dependency to support building with
--incompatible_disable_starlark_host_transitions

Contributors

Alexandre Rostovtsev

v0.6.1

Compare Source

Bugfix release: fix rules_jvm_external pin warnings.

This release temporarily restores compatibility with Bazel 5 (manually tested).
Note that normally we only test Stardoc with the current stable Bazel and with
Bazel at HEAD - not with older releases. We make no promises about maintaining
compatibility with Bazel 5.

Contributors

Alexandre Rostovtsev

v0.6.0

Compare Source

New Features

• Stardoc no longer escapes HTML tags in documentation. Feel free to
  use HTML formatting in your docs! We now also have much-improved
  rendering for fenced code blocks in attribute docs, and render attribute
  default values using Markdown instead of HTML markup. (#​161, #​167)

• Stardoc now dedents and trims all doc strings - not only in macros (#​170).
  This means you can have

  my_rule = rule(
      doc = """
      This is my rule.
  
      Here is more info about it.
  
      ...
      """,
      ...
  )

  and Stardoc will dedent and trim the doc to

  This is my rule.
  
  Here is more info about it.
  
  ...
  

• When using Bazel 7 or newer (or current Bazel HEAD), Stardoc will by
  default use the native starlark_doc_extract rule internally (#​166).

  This means, in particular:

  • correct default values for rule attributes in all cases
  • documentation for module extensions
  • more complete documentation for repository rules
  • by default (this can be turned off via render_main_repo_name = False),
    we will render labels in your main repo with a repo component: your
    main module name (when using bzlmod) or WORKSPACE name (#​168).

  You may temporarily disable the new extractor by calling Stardoc with
  use_starlark_doc_extract = False. However, after Bazel 7 is released,
  we plan to remove this argument and always use the new extractor.

Incompatible Changes

• The Markdown renderer now uses Google EscapeVelocity instead of Apache
  Velocity for templating. The templating engines are almost compatible,
  with the exception of escapes in string literals: if in your template you
  had a string literal with a character escape, you would need to expand it.

  For example, instead of

  ${funcInfo.docString.replaceAll("\n", " ")}

  you would need

  ${funcInfo.docString.replaceAll("
  ", " ")}

• When using the native starlark_doc_extract extractor, Stardoc requires
  two additional templates: repository_rule_template and
  module_extension_template. If you are using custom templates, you will
  probably want to define these, following the examples in
  stardoc/templates/markdown_tables.

• When using the native starlark_doc_extract extractor, Stardoc cannot
  document generated .bzl files any more - because Bazel cannot load()
  generated .bzl files.

Other Notable Changes

• The Markdown renderer's source now lives in the Stardoc repo; we build the
  renderer from source instead of using a bundled jar. Unfortunately, if you
  are not using bzlmod, this requires a rather complicated WORKSPACE setup;
  see https://github.com/bazelbuild/stardoc/releases/tag/0.6.0

Contributors

Alexandre Rostovtsev, Fabian Meumertzheim